package com.demo.framework.db;

import java.util.List;

import android.content.ContentValues;
import android.database.Cursor;

/**
 * 数据库访问模块接口
 */
public interface DatabaseAccess {
    
    /**
     * 开始事务
     */
    public void beginTransaction();

    /**
     * 设置事务成功
     */
    public void setTransactionSuccessful();

    /**
     * 结束事务
     */
    public void endTransaction();

    /**
     * 关闭数据库
     */
    public void closeDB();
    
    /**
     * 创建一个新的 Unique Identifier
     * @return
     */
    public String newUniqueID();

    /**
     * 添加触发器
     * @param trigger
     */
    public void addTrigger(DatabaseTrigger trigger);

    /**
     * 设置是否抛出查询异常
     * @param rethrowException true 查询时异常重新抛出，false 不抛出异常，只返回空结果
     */
    public void setRethrowQueryException(boolean rethrowException);

    // ------------------------------------------------------------------------------
    // 数据库操作
    
    /**
     * 执行sql操作
     * @param sql
     */
    public void execSQL(String sql);

    /**
     * 如果给定表格不存在，创建表格。
     * @param tableName 表名
     * @param columns 列名
     */
    public void createTableIfNoExists(String tableName, String[] columns);

    /**
     * 删除表格。
     * @param tableName
     */
    public void dropTableIfExists(String tableName);

    /**
     * INSERT， 会触发添加的DatabaseTrigger。
     * @param tableName 表名
     * @param values 数据
     * @return
     */
    public long insert(String tableName, ContentValues values);

    /**
     * UPDATE， 会触发添加的DatabaseTrigger。
     * @param tableName 表名
     * @param values 更新数据
     * @param whereClause 更新条件
     * @param whereArgs 更新条件参数
     * @return row id
     */
    public int update(String tableName, ContentValues values,
            String whereClause, String... whereArgs);

    /**
     * INSERT， 不会触发添加的DatabaseTrigger。
     * @param tableName
     * @param values
     * @return 更新的行数
     */
    public long insertWithoutTrigger(String tableName, ContentValues values);

    /**
     * UPDATE， 不会触发添加的DatabaseTrigger。
     * @param tableName
     * @param values
     * @param whereClause
     * @param whereArgs
     * @return
     */
    public int updateWithoutTrigger(String tableName, ContentValues values,
            String whereClause, String... whereArgs);

    /**
     * INSERT, 不抛出异常。
     * @param tableName
     * @param values
     * @return
     */
    public long insertQuitely(String tableName, ContentValues values);

    /**
     * UPDATE，不抛出异常。
     * @param tableName 
     * @param values
     * @param whereClause
     * @param whereArgs
     * @return
     */
    public int updateQuitely(String tableName, ContentValues values,
            String whereClause, String... whereArgs);

    // ------------------------------------------------------------------------------
    // 查询操作
    
    /**
     * 执行SQL查询，使用给定的RowHandler处理查询结果中每一行记录。
     * @param sql SQL语句
     * @param rh RowHandler
     * @param args SQL语句参数
     */
    public void queryWithHandler(String sql, QueryResultHandler<Void> rh, String... args);
    
    /**
     * 执行SQL查询，返回Cursor
     * @param sql SQL语句
     * @param args SQL语句参数
     * @return
     */
    public Cursor query(String sql, String... args);

    /**
     * 执行SQL查询，使用给定的ObjectQuery<T>将查询结果中第一行记录转换为类型为 T 的对象。
     * @param sql SQL语句
     * @param objq ObjectQuery<T>
     * @param args SQL语句参数
     * @return 查询结果不为空类型为 T 的对象,或null。
     */
    public <T> T queryObject(String sql, QueryResultHandler<T> objq, String... args);

    /**
     * 执行SQL查询，使用给定的ObjectQuery<T>将查询结果中每一行记录转换为类型为 T 的对象。
     * @param sql SQL语句
     * @param objq ObjectQuery<T>
     * @param args SQL语句参数
     * @return 
     */
    public <T> List<T> queryList(String sql, QueryResultHandler<T> objq,
            String... args);
    
    /**
     * 执行SQL查询，将查询结果中每一行记录转换为字符串数组。
     * @param sql SQL语句
     * @param args SQL语句参数
     * @return List<String[]>
     */
    public List<String[]> queryStringsList(String sql, String... args);
    
    /**
     * 执行SQL查询，将查询结果中第一行记录转换为字符串数组。
     * @param sql SQL语句
     * @param args SQL语句参数
     * @return String[]
     */
    public String[] queryStrings(String sql, String... args);
    
    /**
     * 执行SQL查询，返回整数结果。
     * @param sql SQL语句
     * @param args SQL语句参数
     * @return
     */
    public int queryNumber(String sql, String... args);
}

// ----------------------------------END---------------------------------------//